Manual de usuario de la herramienta de gestión de cambios en bases de datos

Introducción

Objetivo del documento

El objetivo de este documento es proporcionar una guía de referencia para los equipos de desarrollo que utilicen Liquibase como herramienta de gestión de cambios en bases de datos dentro de la Plataforma CI/CD corporativa.

El manual describe cómo deben estructurarse los repositorios que gestionan cambios en base de datos, así como las normas y buenas prácticas que deben seguir los equipos para garantizar una gestión controlada, versionada y reproducible de dichos cambios.

Este documento forma parte de la documentación asociada a la iniciativa Impulso DevSecOps, cuyo objetivo es promover la adopción de prácticas de integración continua, despliegue continuo y automatización dentro del ciclo de vida del software.

Público destinatario

Este documento está dirigido a:

• equipos de desarrollo responsables de aplicaciones que gestionan cambios en bases de datos
• responsables tecnológicos de proyectos que deben incorporar sus aplicaciones en la Plataforma CI/CD corporativa

El documento está orientado al uso técnico de Liquibase desde el punto de vista del desarrollo, y no cubre los procedimientos operativos del pipeline ni la gestión de incidencias en producción.

Alcance del documento

El manual cubre los siguientes aspectos:

• conceptos básicos de Liquibase
• estructura estándar de repositorios para gestionar cambios en base de datos
• inicialización de proyectos con Liquibase
• creación y gestión de changesets
• uso del versionado y etiquetado de cambios
• definición de rollback en los cambios
• normas y principios de uso dentro del entorno corporativo

Quedan fuera del alcance de este documento:

• la operación del pipeline CI/CD
• la gestión de incidencias en despliegues
• los procedimientos de rollback ejecutados por el equipo de operaciones

Estos aspectos se describen en el Manual de Operaciones de Liquibase.

Liquibase en la Plataforma CI/CD corporativa

Descripción del proceso

Liquibase se integra de la Plataforma CI/CD corporativa como mecanismo para la gestión, ejecución y control de los cambios en la base de datos asociados a las aplicaciones.

Su ejecución se realiza de forma automatizada dentro del pipeline, garantizando que los cambios en la base de datos se aplican de forma controlada, trazable y alineada con el despliegue del artefacto de aplicación.

El pipeline se compone de varias fases diferenciadas, en las que Liquibase interviene principalmente en las fases de sincronización de base de datos.

Fases del pipeline

El flujo del pipeline se divide en las siguientes fases:

1. CI

En esta fase se realiza:

• la construcción del artefacto de la aplicación
• la ejecución de pruebas de calidad y seguridad (QA/Sec)
• la publicación del artefacto generado

Si la fase de CI no se completa correctamente, el pipeline finaliza sin continuar con el resto de fases.

2. PreSync

La fase PreSync es la encargada de ejecutar los cambios en la base de datos mediante Liquibase antes del despliegue del artefacto.
El flujo es el siguiente:

1. Se verifica si existe la carpeta de configuración de Liquibase en el repositorio.
   1. Si no existe, se continúa directamente con la fase de despliegue sin ejecutar cambios en base de datos.
   2. Si existe, se continúa con el proceso de sincronización.
2. Se guarda el TAG actual de la base de datos.
   1. Este TAG permite identificar el estado previo de la base de datos y se utilizará en caso de rollback.
3. Se ejecuta el proceso de actualización de base de datos mediante Liquibase (update). Liquibase ejecuta los changesets pendientes definidos en los changelogs, respetando el orden establecido y evitando la reejecución de cambios ya aplicados.
4. Se evalúa el resultado de la ejecución:
   1. Si la ejecución es correcta:
      1. Se genera un nuevo TAG de base de datos con formato X.Y.Z-SNAPSHOT, representando el nuevo estado tras la aplicación de cambios.
      2. Se continúa con la fase de despliegue.
   2. Si la ejecución falla:
      1. Se realiza un rollback de la base de datos al último TAG válido.
      2. El pipeline finaliza en esta fase.

3. Sync

En esta fase se realiza el despliegue del artefacto de la aplicación en el entorno correspondiente.

1. Se ejecuta el despliegue del artefacto.
2. Se evalúa el resultado:
   1. Si el despliegue falla:
      1. Se ejecuta un rollback de la base de datos al último TAG registrado.
      2. El pipeline finaliza.
   2. Si el despliegue es correcto:
      1. Se continúa con la fase PostSync.

4. PostSync

La fase PostSync valida el estado final del sistema tras el despliegue y determina si el proceso puede considerarse exitoso.

El flujo es el siguiente:

1. Se verifica si existe un Job de PostSync.
   1. Si no existe:
      1. Se podrán ejecutar pruebas manuales o gestionar posibles rollbacks de forma manual.
      2. Se requiere validación por parte del equipo de operaciones.
   2. Si existe:
      1. Se ejecuta el proceso definido.
2. Se evalúa si el PostSync es bloqueante:
   1. PostSync bloqueante
      1. Se ejecutan pruebas automáticas (por ejemplo, Selenium).
      2. Se evalúa el resultado:
         1. Si falla:
            1. Se realiza rollback de la base de datos al último TAG.
            2. El pipeline finaliza.
         2. Si es correcto:
            1. Se continúa con el cierre del proceso.
   2. PostSync no bloqueante
      1. Se genera directamente un TAG de versión final (X.Y.Z).
      2. Se ejecutan las pruebas (no bloqueantes).
      3. El resultado de estas pruebas no impide la finalización del pipeline.
3. Intervención de operaciones:
   1. En determinados casos (por ejemplo, ejecución manual o situaciones excepcionales), el equipo de operaciones puede intervenir para:
      1. validar el resultado
      2. decidir si continuar o ejecutar un rollback
4. Finalización:
   1. Si todo es correcto, se genera el TAG final de versión (X.Y.Z) y el pipeline finaliza con estado OK.
   2. En caso de error, se realiza rollback y el pipeline finaliza en estado fallido.

Gestión de TAGs de base de datos

Durante el pipeline se utilizan TAGs de Liquibase para gestionar el estado de la base de datos:

• TAG anterior → punto de rollback
• TAG snapshot → estado tras PreSync
• TAG final → versión estable tras despliegue

Estos TAGs permiten:

• realizar rollback controlado
• garantizar trazabilidad
• asegurar la coherencia entre versiones

Consideraciones generales

• Los cambios en base de datos se aplican siempre antes del despliegue de la aplicación.
• Cualquier error en PreSync o Deploy implica rollback automático.
• El PostSync permite validar funcionalmente el sistema antes de dar por finalizada la versión.
• El pipeline garantiza la alineación entre la versión del componente y el estado del historial de cambios en base de datos, definido por el conjunto de changesets aplicados
• El equipo de operaciones puede intervenir en puntos críticos del flujo.

Conceptos básicos de Liquibase

Liquibase se basa en un conjunto de conceptos fundamentales que permiten definir, versionar y aplicar cambios en bases de datos de forma controlada.

Changelog

El changelog es un archivo que define los cambios que deben aplicarse a la base de datos.

En esta arquitectura, el fichero root_changelog.xml actúa como punto de entrada principal, referenciando el resto de changelogs del proyecto.

Este archivo actúa como punto de entrada para Liquibase y contiene referencias a uno o varios changelogs.

El changelog se define en formato XML.

En la práctica, el changelog permite organizar y estructurar los cambios que deben aplicarse en la base de datos de una aplicación.

Changeset

Un changeset representa una unidad individual de cambio en la base de datos.

Cada changeset define una modificación concreta, como por ejemplo:

• creación de una tabla
• modificación de una columna
• creación de un índice
• inserción de datos iniciales

Cada changeset dispone de un identificador único que permite a Liquibase registrar qué cambios han sido aplicados en la base de datos.

La unicidad de un changeset vendrá determinada por la combinación de los atributos identificador (id) y el atributo “autor” (author).

• Cada changeset debe incluir:
• un identificador único (id)
• un autor (author)
• una o varias instrucciones de cambio
• Un bloque de rollback

Ejemplo de changeset:

<changeSet id="1.0.0-1" author="nombre.apellido1.apellido2">
   <comment>Descripción del cambio</comment>
   <createTable tableName="example">
       <column name="id" type="INT"/>
   </createTable>
   <rollback>
       <dropTable tableName="example"/>
   </rollback>
</changeSet>

Es recomendable incluir comentarios descriptivos que expliquen el propósito del cambio.

Liquibase mantiene esta información en tablas internas, principalmente DATABASECHANGELOG y DATABASECHANGELOGLOCK.

Gracias a este mecanismo, Liquibase puede determinar qué cambios deben ejecutarse y evitar la ejecución repetida de cambios ya aplicados.

Los changesets deben definirse de forma incremental y no deben modificarse una vez ejecutados en un entorno, ya que esto puede provocar inconsistencias entre entornos y errores en la ejecución de Liquibase.

Tablas internas de Liquibase

Liquibase utiliza tablas internas en la base de datos para gestionar el estado de los cambios aplicados.

Las principales tablas son:

• DATABASECHANGELOG: almacena el historial de changesets ejecutados, permitiendo a Liquibase identificar qué cambios ya han sido aplicados.
• DATABASECHANGELOGLOCK: gestiona el bloqueo de la base de datos para evitar ejecuciones concurrentes de Liquibase.

Estas tablas son creadas automáticamente por Liquibase durante su primera ejecución.

Su uso permite:

• mantener la trazabilidad de los cambios
• garantizar que los changesets no se ejecutan más de una vez
• evitar ejecuciones simultáneas sobre la misma base de datos

Estas tablas no deben ser modificadas manualmente.

Rollback

El rollback permite revertir cambios previamente aplicados en la base de datos.

Liquibase permite definir la lógica de rollback asociada a un changeset, de forma que el sistema pueda deshacer los cambios en caso de error durante el despliegue o durante la ejecución del pipeline.

La definición de rollback es una práctica que permite mejorar la capacidad de recuperación ante incidencias.

Tags y versionado

Liquibase permite etiquetar el estado de la base de datos mediante tags.

Un tag representa un punto concreto en el historial de cambios aplicados y permite identificar la versión de la base de datos en un momento determinado.

El uso de tags facilita la ejecución de operaciones como:

• rollback hasta una versión anterior
• identificación de versiones de base de datos
• sincronización entre artefacto y base de datos

Dentro del pipeline CI/CD corporativo, los tags se utilizan para mantener alineadas las versiones de la base de datos con las versiones de los artefactos desplegados.

Los tags DEBEN corresponderse con versiones del componente cuando existan cambios en base de datos.

Estructura estándar del repositorio Liquibase

Para facilitar la integración con la Plataforma CI/CD corporativa, los repositorios que utilicen Liquibase deben seguir una estructura homogénea que permita localizar fácilmente los cambios de base de datos y gestionar su evolución.

La estructura del repositorio está definida en la Norma de uso de la herramienta de gestión de cambios en bases de datos en la Plataforma CI/CD corporativa en la directriz DIR_04 Estructura de directorios y ficheros.

Changelog raíz

El archivo root_changelog.xml actúa como punto de entrada para la ejecución de los cambios en base de datos.

Este fichero no contiene changesets directamente, sino que incluye uno o varios ficheros de changelog que, a su vez, contienen los changesets definidos en el proyecto.

Este enfoque permite:

• organizar los cambios de forma modular
• mantener una estructura escalable
• facilitar la evolución del sistema

Ejemplo simplificado:

<databaseChangeLog>
   <include file="changelogs/changelog-1.0.0/changelog-1.0.0.xml"/>
</databaseChangeLog>

Organización de changelogs

Los changelogs se organizan de forma jerárquica:

• el root_changelog.xml actúa como punto de entrada
• los changelogs intermedios agrupan changesets
• los changesets contienen los cambios concretos

Esta estructura permite desacoplar la organización lógica de los cambios de su ejecución.

Inicialización de proyectos con Liquibase

Antes de comenzar a gestionar cambios en una base de datos mediante Liquibase, es necesario inicializar el repositorio y preparar la estructura básica de changelogs.

Existen dos escenarios habituales de inicialización.

Inicialización de una base de datos existente

Cuando una aplicación ya dispone de una base de datos previamente creada, el primer paso consiste en generar un estado inicial que represente la estructura actual de la base de datos.

Este estado inicial se puede obtener mediante herramientas de generación de changelog proporcionadas por Liquibase.

El objetivo es capturar la estructura existente para que Liquibase pueda comenzar a gestionar los cambios a partir de ese momento.

Una vez generado el changelog inicial:

• se incorpora al repositorio
• se establece como punto de partida del historial de cambios
• los cambios posteriores se gestionan mediante nuevos changesets

Generación del changelog inicial mediante generate-changelog

Liquibase proporciona el comando generate-changelog para facilitar la incorporación de bases de datos ya existentes al control de cambios gestionado mediante Liquibase.

Este comando permite analizar la estructura actual de una base de datos y generar automáticamente un archivo de changelog que representa su estado inicial.

El changelog generado incluye información estructural como, entre otros elementos:

• tablas existentes
• columnas y tipos de datos
• claves primarias
• claves foráneas
• índices y restricciones
• vistas (según el motor de base de datos)

El objetivo de este proceso es capturar un estado inicial (baseline) de la base de datos a partir del cual Liquibase pueda comenzar a gestionar su evolución.

Consideraciones importantes sobre generate-changelog

El uso de generate-changelog debe tener en cuenta las siguientes consideraciones:

• el comando no aplica cambios sobre la base de datos
• la base de datos no se modifica durante la ejecución del comando
• el changelog generado describe el estado actual del esquema, no su historial
• el resultado debe considerarse un punto de partida, no un historial completo de cambios

El changelog generado no debe ejecutarse directamente contra la misma base de datos desde la que se ha generado, ya que las estructuras descritas ya existen.

Uso del changelog generado como baseline

Una vez generado el changelog inicial:

• el archivo debe incorporarse al repositorio de código
• se establece como changelog base del proyecto
• los cambios estructurales posteriores se definen mediante nuevos changesets

Para que Liquibase tenga constancia de que este estado inicial ya está presente en la base de datos, se debe realizar una sincronización del changelog sin ejecutar los cambios, marcándolos como ya aplicados con el comando changelog-sync.

Este enfoque permite que:

• Liquibase comience a gestionar la base de datos a partir de ese punto
• se mantenga la trazabilidad de los cambios futuros
• se evite la reejecución de estructuras existentes

A partir de la inicialización, todos los cambios evolutivos de la base de datos deben gestionarse exclusivamente mediante Liquibase, siguiendo las normas y principios definidos en este documento.

Inicialización de una base de datos nueva

En el caso de aplicaciones nuevas, la base de datos puede construirse directamente a partir de changesets definidos en el repositorio.

En este escenario:

• el changelog inicial define la estructura base de la base de datos
• los changesets posteriores representan la evolución del esquema de datos

Este enfoque permite que cualquier entorno pueda recrear la base de datos completa ejecutando los changelogs definidos en el repositorio.

Desarrollo y evolución de cambios

Una vez inicializado el proyecto, los cambios en la base de datos deben gestionarse mediante changesets definidos en los archivos de changelog.

Creación de nuevos changesets

Cada modificación que afecte a la estructura de la base de datos debe definirse mediante un nuevo changeset.

Algunos ejemplos de cambios que deben gestionarse mediante changesets son:

• creación de tablas
• modificación de columnas
• creación de índices
• inserción de datos iniciales
• eliminación de estructuras obsoletas

Cada changeset debe tener un identificador único que permita a Liquibase registrar su ejecución.

Versionado de cambios

Los cambios en la base de datos deben evolucionar de forma coordinada con las versiones de la aplicación.

Cada versión del componente desplegado debe corresponderse con un estado concreto del historial de cambios en base de datos, definido por el conjunto de changesets aplicados.

El pipeline CI/CD se encarga de aplicar automáticamente los cambios pendientes durante la fase de sincronización de base de datos.

El modelo de gestión de cambios es incremental, incorporando nuevos changesets sin modificar los existentes. Este modelo garantiza que el historial de cambios es inmutable, trazable y reproducible en cualquier entorno.

Uso del rollback desde el punto de vista de desarrollo

Liquibase permite definir mecanismos de rollback que facilitan la reversión de cambios en caso de error.

Definición de rollback en changesets

Los changesets deben incluir la lógica necesaria para revertir los cambios que aplican.

Por ejemplo, si un changeset crea una tabla, el rollback correspondiente podría consistir en eliminar dicha tabla.

Definir rollback en los changesets permite automatizar la recuperación ante incidencias durante el proceso de despliegue.

Consideraciones sobre rollback

No todos los cambios en base de datos pueden revertirse fácilmente.

En algunos casos, especialmente cuando se producen transformaciones de datos, el rollback puede requerir mecanismos adicionales.

Por este motivo es importante analizar cuidadosamente cada cambio antes de aplicarlo.

Casos de uso habituales

Durante el desarrollo de una aplicación pueden darse diferentes escenarios relacionados con la evolución de la base de datos.

Aplicación de nuevos cambios

Cuando se introducen nuevos cambios en la base de datos, estos se añaden como nuevos changesets en los changelogs del repositorio.

Durante la ejecución del pipeline, Liquibase detectará qué changesets no han sido aplicados aún y procederá a ejecutarlos.

Creación de tablas nuevas

Uno de los casos más habituales en la evolución de una base de datos es la creación de nuevas tablas.

Este tipo de cambio debe definirse mediante un changeset específico que describa la estructura de la tabla.

Ejemplo de changeset en formato XML:

<changeSet id="1.0.0-1" author="nombre.apellido1.apellido2">
   <createTable tableName="usuarios">
       <column name="id" type="INT">
           <constraints primaryKey="true" nullable="false"/>
       </column>
       <column name="nombre" type="VARCHAR(100)" />
       <column name="email" type="VARCHAR(150)" />
   </createTable>
   <rollback>
       <dropTable tableName="usuarios"/>
   </rollback>
</changeSet>

Este enfoque permite:

• crear estructuras de forma controlada
• mantener trazabilidad del cambio
• definir su reversión mediante rollback

Inserción de datos

Liquibase permite gestionar también la inserción de datos mediante changesets.

Este tipo de cambios es habitual para:

• carga de datos iniciales
• configuración de catálogos
• datos necesarios para el funcionamiento de la aplicación

Ejemplo de inserción de datos:

<changeSet id="1.0.0-2" author="nombre.apellido1.apellido2">
   <insert tableName="usuarios">
       <column name="id" valueNumeric="1"/>
       <column name="nombre" value="Juan Pérez"/>
       <column name="email" value="juan.perez@example.com"/>
   </insert>
   <rollback>
       <delete tableName="usuarios">
           <where>id = 1</where>
       </delete>
   </rollback>
</changeSet>

Es recomendable:

• evitar grandes volúmenes de datos en changesets
• utilizar scripts externos cuando el volumen sea elevado.

Uso de ficheros SQL en changelog

Liquibase permite utilizar scripts SQL externos dentro de los changesets.

Esto resulta útil cuando:

• se reutilizan scripts existentes
• se manejan cambios complejos
• se prefiere trabajar directamente en SQL

Ejemplo de uso de fichero SQL:

<changeSet id="003-create-index" author="nombre.apellido1.apellido2">
   <sqlFile path="scripts/sql/create_index_usuarios.sql"/>
   
   <rollback>
       <sql>DROP INDEX idx_usuarios_email;</sql>
   </rollback>
</changeSet>

Ejemplo de contenido del fichero SQL (create_index_usuarios.sql):

CREATE INDEX idx_usuarios_email ON usuarios(email);

Buenas prácticas en el uso de SQL:

• mantener los scripts organizados en el directorio correspondiente
• evitar lógica compleja difícil de mantener
• definir siempre rollback cuando sea posible

Este enfoque proporciona flexibilidad sin perder el control de cambios que ofrece Liquibase.

Creación de changeset desde base de datos poblada

En escenarios donde ya existe una base de datos con datos y estructura, es posible generar changesets automáticamente a partir de su estado actual.

Liquibase proporciona herramientas como:

• generate-changelog
• diff
• diff-changelog

Ejemplo de uso:

liquibase generate-changelog --outputFile=changelog-inicial.xml

Este proceso permite:

• capturar la estructura existente
• generar un punto de partida (baseline)
• comenzar a gestionar la evolución mediante Liquibase

Tras la generación:

• el changelog debe revisarse manualmente
• se debe ejecutar changelog-sync para marcar los cambios como aplicados

Este enfoque es especialmente útil en procesos de migración a Liquibase.

Desarrollo en paralelo

En entornos de desarrollo es posible que varios equipos trabajen simultáneamente sobre la evolución de la base de datos.

En estos casos es importante coordinar la creación de changesets para evitar conflictos entre cambios concurrentes.

Cambios tras un rollback

Cuando se produce un rollback en el pipeline, los cambios revertidos no deben modificarse directamente.

En su lugar, los nuevos cambios deben introducirse mediante nuevos changesets que reflejen el estado correcto de la base de datos.

Normas y principios de uso

Para garantizar una gestión adecuada de los cambios en base de datos dentro del entorno corporativo se establecen los siguientes principios de uso.

Ver Norma de uso de la herramienta de gestión de cambios en bases de datos en la Plataforma CI/CD corporativa.